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1. Introduction 


AdvoCATE User Guide 


Introduction 


• AdvoCATE Basic Vision 

- To automate the creation, manipulation and management of large-scale assurance cases based on a 
formal theory of argument structures 

• Main purpose 

- Creating and manipulating argument structures for safety/assurance cases using the Goal 
Structuring Notation (GSN) 

- A test bed and proof-of-concept for the formal theory of argument structures 

• AdvoCATE is available for 

- Windows 7 

- Macintosh OS X 

- Linux 

• Eventually, AdvoCATE will 

- Serve as a dashboard for safety related information 

- Provide an infrastructure for safety decisions and management 
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2. Installation, Launch & Configuration 


AdvoCATE User Guide 


Installation 


• Unzip the installation archive into your preferred folder 

• Launch the executable file 

• On launch, specify a path in the workspace launcher dialog box to create a new workspace 


© O O Workspace Launcher 

Select a workspace 

AdvoCATE stores your projects in a folder called a workspace. 
Choose a workspace folder to use for this session. 


Workspace: /Users/gpai/eclipse-workspaces/workspace| 


Browse... 


Use this as the default and do not ask again 


Cancel 



• A workspace is a folder that AdvoCATE uses to cache tool settings and the state 

- Workspaces can be periodically deleted to remove cached settings 

• AdvoCATE will launch in the AdvoCATE perspective 

- The AdvoCATE perspective is a customized arrangement of IDE windows which you will use to 
create, manipulate and manage argument structures and patterns 
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AdvoCATE Perspective 


AdvoCATE - AdvoCATE - /II sera /qpai/ed ipse- works paces /workspace 


„n* 

Fff | AOVOCATI | 

Project Explorer £3 0 % ^ □ 

D □ 

Project Explorer 

Canvas and Palette panels appear here* 

panel 

*After creating a new project and adding new arguments / patterns 

0 Miniature View E2 a B 

O Detail £3 ' Problems I u I Queries ^ Metrics IT Tables '®T Table Preview x Verification Reoori Specification T = D 


Nothing selected 

Miniature View 

Editing Panels: Detail, Queries, Metrics, Tables, Verification, 

panel 

Report Specification 


Status Panels: Problems, Table Preview 
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AdvoCATE Perspective - Canvas and Palette 


Canvas and Palette for Arguments 


Canvas and Palette for Patterns 









W Palette |> 

Select 









□ Marquee 

& Connections <3 















* IsSolvedEy 
InContextQf 

* HiLink 

















& Objects <£■ 

□ Coal 









^Assumption 
□ Context 
Q Evidence 
■S- 5 Justification 

7 Strategy 

















gHiCoal 
F HiEvidence 


List of availabl< 

3 patterns — 3 

FI Hi Strategy 

C3 Patterns cc- 

^ demo Pattern! 



{} Palette [> 

5elect 


[ j Marquee 

& Connections <£■ 

A J ^ 1— 1 I 

IsSolvedEy 
~ 1 k InContextOf 
^ HiLink 

Additional 

> 

connection 

► ^Choice 

& Objects <05 


□ Coal 
^ Assumption 


■ ■ Context 
Q Evidence 

■ J: ' Justification 
□ strategy 
F Hi Coal 



[e | HiEvidence 

|s | Hi Strategy 


• Drag and drop objects and connections from the palette onto the canvas 

- The palette for arguments lists available patterns, i.e., a pattern library 

- The palette for patterns contains one additional choice connection 
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AdvoCATE Perspective - Canvas and Palette 


Canvas and Palette for Modules and Module Contracts 





is Palette > 

Select 




[~j Marquee 

\>p Connections 


W Oil:! 1 V QO 


IsSolvedBy 
InContextOf 
~ * HiLink 




Objects <0 

□ Goal 





Assumption 
Context 
( ) Evidence 
J Justification 
Strategy 









[ 1 AwayGoal 
( — ] AwayContext 

J 

Additional 

Nodes 

* 

> 

1 i AwaySolution 
E □ ModuleRef 
Q ModuleContractRef 
fiF] HiGoal 
fTI HiEvidence 




|7~| Hi Strategy 

Patterns 




demoPatternl 


The palette contains additional node elements for 
module and contract module diagrams 

- Module references 

- Contract module references 

As before, drag and drop objects and 
connections from the palette onto the canvas 


AdvoCATE User Guide 


9 


AdvoCATE Preferences 


« i 

« n 





AdvoCATE 


File Edit View Navigate Search Project Run 


About AdvoCATE 


Preferences... 

Services 

► 1 

Hide AdvoCATE 

8€H 

Hide Others 

M8€H 

Show All 


Quit AdvoCATE 

3SQ 


AdvoCATE - platform: /resource/acUse 


a % 


[£| demoArgumentl £2 


osx 


Preferences 



Advocate -AdvoCATE 


File Edit Navigate Search Project Run 

- I I 4 _ " I 


HI 


IJ] Project Explorer £3 


Windows 7 


Help 


New Window 
New Editor 


If 

Open Perspective 

► 

Show View 

► 

Customize Perspective. . 


Save Perspective As... 


Reset Perspective., 


Close Perspective 


Close All Perspectives 


Navigation 

► 

^ Preferences 


• AdvoCATE preferences allow the user to 
configure tool settings with respect to 

- Errors / Warnings 

- Styles of the graphical elements 

- Metadata (described later) 

- Queries* 

- Formal tool integration* 

- Other settings elements shown in the 
Preferences window are not currently 
relevant for AdvoCATE 


*Not covered in this user guide 
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Preferences - Global Errors / Warnings 


Preferences 



Note: These preferences apply globally to all 
projects in the workspace 


• AdvoCATE checks well-formedness upon 
saving an argument structure 

• Currently, 3 well-formedness checks are 
available for arguments and patterns: 

- Cyclicity: Presence/absence of 
cycles in the structure* 

- Identifier uniqueness: Unique node 
identifiers 

- Multiple roots: Presence of only a 
single root node 

• Each check has 3 possible values: 

- Error 

- Ignore 

- Warning 

• To alter the defaults, select a value from 
the drop-down list 


• Outcomes of the checks are displayed in 
the Problems panel 

*Cyclic structures are permitted in patterns 
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Preferences - Project Specific Errors / Warnings 


Preferences 


type filter text 

► General 
▼ Advocate 

▼ Build 

Errors /Warnings 

▼ Editor 

▼ Attributes 

Enumerations 

Synonyms 

Styles 

▼ Formal Tools 

AutoCert 

Queries 

► Help 

► Install/Update 
►Java 

Mission Time 

► Model Validation 

► Run/Debug 

► Team 


Errors/Warnings 


Configure Project Specific Setting s.. 

Select the severity level for the following optional problems: 


type filter text (use ~ to filter on preference values, e.g. -ignore or -off) 

check 


Structure well-formedness < 

Cyclicity 

Identifier uniqeness 
Multiple roots 

Pattern well-formedness c 

Cyclicity 

Identifier uniqeness 
Multiple roots 


Project Specific Configuration 

Select the project to configure: 


_ acUserGuide 


Cancel 


OK 


Restore Defaults 


Cancel 


Apply 


OK 


Properties for acUserGuide {Filtered) 


type filter text 

▼ Advocate 

Errors /Warning 5 


Errors /Warnings 


Enable project specific settings 



Select the severity level for the following oplLoi 

type filter text {use - to filter on preference values, e.g, -ignore or -off) 


Structure well-formedness check 

Cyclicity 

Error 

V 

Identifier uniqeness 

Error 

: 

Multiple roots 

Error 


Pattern well-formedness check 

Cyclicity 

Ignore 

_L 

identifier uniqeness 

Error 


Multiple roots 

Warning 

y 


To override global preferences and configure 
project-specific settings 

1 . Select Configure Project Specific 

Settings 

2. Select a project from the listed projects 

3. By default, project specific settings are 
disabled 


Restore Defaults Apply 


<D 


Cancel OK 
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Preferences - Project Specific Errors / Warnings (Cont’d.) 


o 


Properties for acUserCuide (Filtered) 


[type filter text 

▼ Advocate 

Errors/Warnings 


<2> 


Errors/Warnings 


>/ Enable project specific settings 


< 


Select the severity level for the following optional problems: 


type filter text (use ~ to filter on preference values, e.g. -ignore or -off) 

r Structure well-formedness check 


Cyclicity 

Identifier uniqeness 
Multiple roots 

Pattern well-formedness check 

Cyclicity 

identifier uniqeness 
Multiple roots 


✓ Error . 

Warning 


Error 


Ignore 


Error 


Warning 


Restore Defaults 


Cancel 


Apply 


OK 




4. Enable project specific settings by 
selecting the check box 

5. Update the default values by selecting a 
value from the drop-down list. As in the 
global preferences, project-specific well- 
formedness checks have 3 possible 
values 

- Error 

- Ignore 

- Warning 


Note: 

These preferences can also be accessed 
through Project properties 
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Preferences - Styles 


type filter text 


Styles 


► General 
▼ Advocate 


Dement: 


Preferences 




▼Build 

Errors /Warnings 
▼ Editor 

►Attributes 

Styles 

► Formal Tools 
Queries 

► Help 

► Install /Update 
►java 

► Model Validation 

► Run/Debug 

► Team 



Restore Defaults Apply 


© 


Cancel OK 


• Nodes are colored blue by default 

• Links are colored black by default 

• To change the default value 

1 . Select a node / link in the Element 
list 

2. Then click the Color button to 
choose a color 


J Preferences 

type hiier text Styles 




► General 
▼Advocate 

▼Build 

Errors /Warnings 
▼ Editor 

► Attributes 
Styles 

► Formal Tools 
Queries 

► Help 

► Install /Update 
►java 

Mission Time 

► Model Validation 

► Run/Debug 

► Team 


Element 



Restore Defaults Apply 


© 


Cancel 0< 
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3. Projects 
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Overview 


• Create an AdvoCATE Project to organize a safety / assurance case 

• Projects can contain 

- Diagram file types with the extension . argument 

• These diagrams can be 

- (Non modular) Argument structures 

- Module diagrams: An argument structure within a module 

- Contract module diagrams: An argument structure within a contract module 

- Diagram file types with the extension .pattern 

• These diagrams are non modular argument patterns 

- Auto-generated output, e.g., Views, Reports, Metrics 

- Folders 

- Other file types referenced by nodes in the argument structure representing 

• Documents: e.g., PDF files, MS Word Documents, Text files, etc. 

• Parameter values for pattern instantiation, e.g., in CSV files 

• Spreadsheets, e.g., MS Excel files 

• Web-pages, e.g., HTML files, etc. 
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Create a New AdvoCATE Project 


£ AdvoCATE 

H Edit Navigate Search 

Project Run Window Help 

« n o 

‘ 

New 

XXN ► ™ 

Advocate Project 

Ud' 3 ’ 

Open File... 


Tj Project... 


Close 

XW 


Ci Project Explorer X 

Close All 

OXW 

L_j Folder 




O File 


Save 

XS 

c Argument Structure 


Save As... 


B Argument Pattern 


Save All 

OXS 

Sf Safety Case Module 


Revert 


If Safety Case Module Contract 


Move... 


n Other... SIN 


Rename... 

F2 ^ 



Refresh 

F5 



Convert Line Delimiters To 

► 



83 Print... 

XP 



Switch Workspace 

► 



Restart 




in Import... 




Export... 




Properties 

XI 



ft AdvoCATE File 

Edit Navigate Search Project Run Window Help 

1* e o 

AdvoCATE - AdvoCATE - /Use 


> -• • ■ -i 


I flr Advocate Project 


r* Project... 

^ v “ □ 

£3 Folder 


[J File 


Argument Structure 


K Argument Pattern 


SSf Safety Case Module 


If Safety Case Module Contract 


n Other... XN 





1 


To create a new project, either 

1 . Select File > New > 
Advocate Project Or 

2. Select the New icon 


Note: 

The same steps can be used 
also to create new 

A. Argument structures 

B. Argument patterns 

C. Modules 

D. Contract modules 
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Create a New AdvoCATE Project 


New Project 


O O 


New Project 


Project 

Create a new project resource. 



Project 

Create a new project resource. 




© 


Cancel Finish 



1 . By default the location of a new project is in the workspace. 

2. We recommend selecting a different location by unchecking the default location option as 
workspaces may need to be periodically deleted 

3. Specify a location using the Browse option 

4. Then ensure that folder in which the project will be located has the same name as the project 
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Import an Existing AdvoCATE Project 


£ AdvoCATE 


Edit Navigate Search Project Run Window 


* n o 




► myACProjea 


New 

X3SN ► | 

Open File... 


Close 

3€W 

! Close All 

osew 

_ Save 

&s 

% Save As... 
Save All 

03€S 

Revert 


Move... 

Rename... 

F2 

<? Refresh 

F5 

Convert Line Delimiters To 

► 

Print... 

3€P 

Switch Workspace 
Restart 

► 

Import... 

Export... 


Properties 

3€l 


f* AdvoCATE File 

Edit Navigate Search Project Run Window 

» 0 0 

AdvoCA 






O Project Explorer S3 
► myACProjea 

New 
Show In 


a 


Copy 

Copy Qualified Name 

Paste 

Delete 


Import. 


xaew ► 

3€C 


3€V 

E> 


Export... 

Refresh 

Load Argument from CSV File 
Translate 

Translate and Merge 


< — 


F5 


To import an existing project, either 

1. Select File > Import OR 

2. Right click the mouse in the Project Explorer and select Import 
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Import an Existing AdvoCATE Project 


O GO Import 

Select 

Create new projects from an archive fife or directory. 
Select an import source; 






type fitter text 


▼ ^General 


^ Archive File 

L 

Existina Protects into Worksoace ^ 


C^File System 
CTj, Preferences 

► ^Install 

► Run/Debug 

► k^Team 



< Back 


Next > 


Cancel 


Finish 



3. Select General > Existing Projects Into Workspace 

4. Specify a path by selecting the Browse button 

5. Select the project(s) to import. We recommend not copying the projects into the workspace as 
workspaces may need to be periodically deleted 
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AdvoCATE Projects 


BOO 



AdvoCATE - AdvoCATE - /Users/gpai/eclipse-workspaces/workspace 




(£j Project Explorer 23 

- R 

^ D □ 


► IcJacUserGuide 





V 

New 

► 



Co Into 




Copy 

sec 



Paste 

XV 



X Delete 

E> 



Move... 




Rename... 

F2 


New and Imported 
Projects displayed in 
the Project Explorer 


3 Miniature View 23 


in Import... 

Export... 

& Refresh fs 

Close Project 

Close Unrelated Projects 

Team ► 

Compare With ► 

Restore from Local History... 
Configure ► 

Load Argument from CSV File 
Translate 

Translate and Merge 


Properties 


I Queries ^ Metrics 


Tables 


L3 myACProject 


Configure project specific properties by 
selecting a project and accessing Properties 
on the right-click menu 

Configure available properties as required 
(Also see AdvoCATE Project preferences ) 


’ type filter text 

► Resource 
▼Advocate 

Errors/Warnings 

Builders 

Project References 
Run/Debug Settings 


j 


Q. Quick Access 


B 


AdvoCATE 


Properties for myACProject 


Errors /Warnings 


C Enable project specific settings 

Confiaure WorksDace Settinas... 

Select the severity level for the following optional problems. 

type filter text (use - to filter on preference values, e.g. ignore or -off) 

Structure well-formedness check 

Cyclicity 

Error t | 

Identifier uniqeness 

Error i | 

Multiple roots 

Error l | 

Pattern well-formedness check 

Cyclicity 

Ignore : i 

Identifier uniqeness 

Error : I 

Multiple roots 

Warning i | 


Restore Defaults Apply 


Cancel 


OK 
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4. Argument Structures and Patterns 
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Create a New Argument Structure 



1^3 Project Explorer S3 B ^ 


► t^acUserGuide 




New 

► 

r3 Project... 


Co Into 


[5 File 


3fc Copy 

XC 

C3 Folder 


Z Paste 

XV 



X Delete 

E> 

B Argument Pattern 


Move... 


Ef Argument Structure 

<— 

Rename... 

F2 

\M Safety Case Module 
W Safety Case Module Contract 

1 

Import... 



ti Export... 


r3 Other... XN 


£ Refresh 

Close Project 

Close Unrelated Projects 

F5 



Team 

► 



Compare With 

► 



° Miniature Vi Restore from Local History... 


£3 Problems Queries Metrics 

Tables 

Configure 

► 



Load Argument from CSV File 



Translate 

Translate and Merge 
Properties 


ng selected 


XI 



O O O New File 

Argument: Structure 

Create a new argument structure fife resource. 


Enter or select the parent folder: 
myACProject 


acCserGuide 
k3 rny AC Project 


2 

Advanced >> 


File name: myArgumcrttl. argument 


1 . Select a project and access the New > Argument 
Structure option in the right-click menu* 

2. Specify a file name; the file extension is automatically 
added 


* A new argument structure can also be created using the New icon, or the File menu 
(See Create a New AdvoCATE Project ) 
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New Argument Structure/Pattern 


• Advocate - platform :/resource/test-proJect-2/ha-pattern.acp#/0 - AdvoCATE 


l a 1 iU 

File Edit View Navigate Search Project Run Window Help 




I I 1 1 

Project Explorer 53 
o fc? gbsaa-sc 
d t3 test-project 

[3] argument-0. acd 
d t3 test-project-2 

[p] ha-pattem.acp 

A 


'XP <p - 


- * * 


e % 


I CPT^ S°o SS I ° ji °fo ol? | § OQI | “ I 

[5] *argument-0 [?) ha -pattern 53 


Quick Access 


Patterns have a “P” in 
their icon 0 


Miniature View 53 


fiV Problems 53 ^1 Tasks □ Properties (D Console 
4 items 
































Each open 
canvas and 

structure/pattern is available as a tab, showing the 
1 the correspondinq palette 






















Structures 

have an “J 

3” in their icon § 





















































5^ | [ B Advocate | 


V Palette 


Select 
[_] Marquee 


& Connections 
* IsSolvedBy 
* > InContextOf 
“ *Hil_ink 
A Choice 
OLoop 


& Objects c 

□Goal 

Assumption 
O Context 
O Evidence 
<3* Justification 
O Strategy 
Q AwayGoal 
Q AwayContext 
Q AwaySolution 
□ HiNode 


Description 

Resource 

Path 

Location 

Type 

d i Infos (4 items) 






i Build [May 02, 2013 11:02:41 AM] 

hdb.acp 

/gbsaa-sc 

Unknown 

Advocate Marker 


i Build [May 02, 2013 11:02:41 AM] 

top.acd 

/gbsaa-sc 

Unknown 

Advocate Marker 


i Build [May 02, 2013 12:02:55 PM] 

argument-0. acd 

/test-project 

Unknown 

Advocate Marker 


i Build [May 02, 2013 12:03:38 PM] 

ha-pattern. acp 

/test-project-2 

Unknown 

Advocate Marker 
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New Argument Structure 


Drag and drop nodes (objects) and links (connections) from the palette onto the canvas to create an argument structure 


• Advocate - platform:/resource/test-project/argument-0.acd#/0 - AdvoCATE 



[ <=» 1 lU 

File Edit View Navigate Search Project Run Window Help 

I r3 ^ y tin Cj 1 '*■ 1 # w 1 f' * ^ ^ <p w * | - | 

5 ffi I Ss & I "S Jts I S m I =■ I <a <a 100% „ 

Quick Access 

1 [ B Advocate 1 


[£] Project Explorer 
t> £3 gbsaa-sc 
a test-project 

Hi argument-O.acd 
d test-project-2 

0 ha-pattern.acp 


Miniature View 



Creating a node 
shows a text editing 
field to enter node 
contents 

Selecting a node 
dynamically lists its 
properties in the 
Properties panel, 
where node contents 
can be edited 


A pattern library 
lists all patterns 
in the current 
and referenced 
projects 
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New Argument Structure 


= □ 

V Palette > 

Select 
[ J Marquee 

GB- Connections <o 

* IsSolvedBy 
InContextOf 
“ * HiLink 

& Objects <o 

C^Goal 
Assumption 
O Context 
O Evidence 
^Justification 
O Strategy 
P AwayGoal 
Q AwayContext 
Q AwaySolution 
□ HiNode 

& Patterns <o 
ha-pattern 


8l/ Problems Tasks n Properties 23 S Console 

Base 

▼ Properties 
Identifier: G1 

Description: System A is acceptably safe 

Attributes: 

Comment: 

Color: [Blue 

Uris: 

Variables: 

OTo Be Instantiated 
|V] To Be Developed 
O Public For Modules 
Interval Values: 

Confidence Variable: 

O References Contract 



*argument-0 23 [?] ha-pattern 



Each node has: 

An auto-generated, but user-editable, 
Identifier 

A Description field to enter node 
contents 

A Metadata field to enter node-specific 
metadata 

User-specified Comments 
A Hyperlinks field to add links to Web 
urls 

Checkboxes to d e corat e annotate 
nodes as 

To be instantiated (Only 
relevant for patterns) 

To be developed 
Public (Only relevant for Goal, 
Context and Evidence nodes to 
make them publicly accessible 
in external module) 

To Be Supported By Contract 
An Association dropdown menu and 
field to indicate whether a node is 
associated with another argument 


Sp e c i f i c nod e s hav e sp e c i f i c add i t i ona l 
f iel ds. 

e .g., “Pub li c for modu le s”, i n Goa l , 

Cont e xt and Ev i d e nc e nod e s to mak e 
th e m pub li c l y acc e ss i b le i n e xt e rna l 
modu le s 
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Node 


Keystroke 


Keyboard Shortcuts 

Keyboard shortcuts are an alternative to using the 
palette for rapidly creating simple argument 
structures/patterns. 

To use keyboard shortcuts to create an argument 
structure 

1 . Make the canvas active by selecting it 

2. Select the appropriate keystroke to create a 
node 

3. By default, a text box appears to specify node 
contents. 

4. Select the next appropriate keystroke to create 
a new node. 

5. AdvoCATE automatically links the two nodes 
with the appropriate link. 

6. Use the arrow keys to select the node to which 
the next new node is to be attached 

7. For example, HI E 0 0 creates the following 
structure 
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Create a New Argument Pattern 

Drag and drop objects (nodes) or connections (links) to create a pattern in the same way as structures 


■ Advocate - platform:/resource/test-proJect-2/ha-pattem.acp#/0 - AdvoCATE 





l <=. 1 dJ Im&mh 

File Edit View Navigate Search Project Run Window Help 

I r3 - y I© o 1 <4 - 1 ^ o - - 1 > | o 1 I | 

Sff & t5 1 D i4 □?! 

? | Eg ODJ | a | €1 <±t 100% - 


Quick Access 

B | [ B Advocate | 


Project Explorer £2 

* £3 gbsaa-sc 

0 hdb.acp 
Hi top acd 

* £3 test-project 

H| argument-O.acd 
d £3 test-project-2 

® ha-pattern. acp 


B % 


Hi argument-0 J [?) *ha-pattern S3 ^ 


Select a link to edit its 
properties in the 
Properties panel in the 
same way as nodes 




Problems .£j] Tasks B Properties S3 § Console 


▼ Properties 

Identifier: Is Solved By 


Strategy SI 


□ Optional 
Multiple 
Lower Bound: 
Upper Bound: 
Link Description: 


1^ Select 
[’] Marquee 


(S Connections «c> 
—* IsSolvedBy 
1 > InContextOf 
* HiLink 
A Choice 
0Loop 


IS Objects <c 

■=1 Goal 
® Assumption 
° Context 
O Evidence 
^ Justification 
O Strategy 
D AwayGoal 
Q AwayContext 
0 AwaySolution 
□ HiNode 


'Q 


'U 
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Argument Patterns - Choices 


To create a choice: 

1 . Select the choice 
connection on the 
palette 

2. Then select the 
source node, and 
drag to the target 
node to create a 
choice link (e.g., G1 
-> S2 as shown) 

3. Re-select the 
choice connection 
on the palette 

4. Then select the 
choice (♦) on the 
canvas and drag to 
the second target 
(e.g., ♦ -> S3 as 
shown), and so on 
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Argument Patterns - Loops 
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Inserting Patterns from the Pattern Library 


» Advocate - platform :/resource/test-proJect/argument-0.acd#/0 - AdvoCATE 


Patterns can be 
added to the 
canvas either 
through 

instantiation (to 
be discussed 
later) or by 
inserting them 
directly from the 
pattern library. 

AdvoCATE 
automatically 
ensures unique 
identifiers by 
auto-generating 
them. 


File Edit View Navigate Search Project Run Window Help 

• ® -j 1 q.- I zf - I * - "5= c= * - | - I <y I . I Si s°5 

[£3 Project Explorer £2 0 ^ ^ “ □ 

i> fc? gbsaa-sc 
* £3 test-project 

@ argument-0. acd 
d £3 test-project-2 

0 ehdb-pattern. acp 
[?| ha-pattern. acp 


:: | £t °ti □?? | ™ [ 
I [?] ehdb-pattern 


[ | or | Q Q, 100% - 














1 G3 I 

I System is 1 
I acceptably | 

1 jafe 1 






J 

r 






^ Miniature View £2 



[j_ Problems Tasks □ Properties £2 (D Console 


1 . Select a pattern 
from the pattern 
library 


i°isn 


© | fE3 Advocate 1 


O Palette 


fe Select 
["] Marquee 


£3 Connections <x> 
* IsSolvedBy 
~~ 1 > InContextOf 
HiLink 


£3 Objects « 

l=lGoal 
® Assumption 
° Context 
O Evidence 
Justification 
O Strategy 
Q AwayGoal 
Q AwayContext 
0 AwaySolution 
BHiNode 


£3 Patterns 
ehdb-pattern 
ha-pattem 


i 

▼ Properties 

x. 2. Click the canvas - 

Identifier: G3 

x: at anv oreferred 

Description: System is acceptably safe 

Attributes: 

—location to insert 

Comment: 

thp Qplpp.tprl 

Color: [Blue 

H 1 VjT OVjflVurUlVyVal 1 

,, 111 I 

Uris: 

pattern 

Variables: 

0To Be Instantiated 
OTo Be Developed 
□ Public For Modules 



AdvoCATE User Guide 


31 



Checking Well-Formedness 


Advocate - platform:/resource/test-project/argument-0.acd#/0 - AdvoCATE 


idea 


File Edit View Navigate Search Project Run Window Help 

| g- © | <4 ^ | # ^ O ^"3 " | cf | <$ 

[^3 Project Explorer £2 B ^ ^ ' 

> fcj? gbsaa-sc 
d £3 test-project 

[§| argument-0. acd 
d £3 test-project-2 

® ehdb-pattern.acp 
[p] ha-pattem.acp 


Double click an 
error to highlight 
it on the canvas 


Miniature View S3 
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^ = □ 

Description 

\ Resource 

Path 

Location 
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d © Errors (2 items) \ 

© Multiple root: G1 

argument-0. acd 

/test-project 

Unknown 

Advocate Marker 


© Multiple root: G3 

argument-0. acd 

/test-project 

Unknown 

Advocate Marker 



Saving an argument structure/pattern will build it, highlighting errors 
and warnings if any 


AdvoCATE User Guide 


32 


Other Ways to Add Nodes 

Another way to add a 

node to a diagram is to: 

1 . Right-click the node. 

2. Select Add Node 
and then any node 
choice. For example, 

Add Node-> Add 
Assumption will 
automatically add an 
Assumption node as 
well as the 
appropriate link to 
the diagram. 
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Other Ways to Add Nodes (Cont.) 


Another way to add a node to a diagram 
is to: 

1 . Right-click a link that is connecting 
two nodes. 

2. Select Insert Node and then the 
option of Goal or Strategy nodes 
before or after the link. For example, 
selecting Insert Node-> Insert 
Strategy before link will produce the 
diagram at right. 



(2j Print... 


Copy 


Paste 


Update 

3£f5 : 

Delete 


Layout 
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Add Node 

► 

Insert Node 

► 

Show/Hide... 
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► 

Save as Pattern 


Export Diagram... 
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Insert Strategy before link 
Insert Goal after link 

Insert Strategy after link 
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Pattern Instantiation 


Instantiating a pattern 
involves systematically 
replacing its node 
parameters with new or 
different values. The 
AdvoCATE tool uses a 
.csv file to specify which 
parameters are 
replaced and with what 
values. 

To instantiate a pattern: 

1. Open the pattern. 

2. Right-click on the 
canvas. 

3. Select Instantiate. 

4. From your local file 
structure, select .csv 
file from which to 
pull values. 


c i) Print... 
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Layout 
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Pattern Instantiation (cont.) 


For example, in the .csv file 

shown here: 

• Row 1 specifies the node 
identifier for nodes in 
the pattern that have 
parameters 

• Row 2 specifies the 
parameter identifiers in 
the corresponding nodes 
as {variable:type} 

• Column 1 shows how the 
specified node will be 
instantiated— i.e. it 
specifies the values of 
the parameters and the 
locations in the instance 
where each node is to be 
joined 
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Cl ^ 


Cl ^ 

Req J :r emenl ID {idl 
:: nt} ho ids 

— > Instantiation — > 

Requirement ID Rl 
holds 


Pattern before instantiation 


Pattern after instantiation 
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Pattern Instantiation (cont.) 

AdvoCATE will automatically open up a 
new tab with the instantiated pattern. 

The instantiated pattern will also appear 
in the project menu on the left as XXX- 
instance-1. argument (where XXX is the 
name of the original pattern). 

The tool features a default auto-layout, 
as shown, but can be manually 
modified. 
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Editing Metadata 

Selecting a node 
dynamically lists its 
properties in the 
Properties panel, where 
node content — like its 
metadata — can be 
edited. 

To add contents to the 
metadata field in the 
node’s Properties panel, 
either: 

• Create and add 
attributes to the node 

OR 

• Add existing 
attributes to the node 


• J>' -I L ■ 


© *argument-demo S3 




Cl 


System A is acceptably safe 


0L Problems B Properties S3 (*)= Parameters Search 

”• Properties 
Identifier: 

Description: 

Metadata: 

Comment: 

Hyperlinks: 

To Be Instantiated 
O To Be Developed 
0 Public 

Q To Be Supported By Contract 
Association: 

Associated Argument: 


0 Advocate 


\} Palette 


fe Se |ect 

[‘J Marquee 


& Connections 
~ * IsSolvedBy 
InContextOf 
~ * HiUnk 


& Objects 
□ Coal 
'A 1 Assumption 
O Context 
Q Evidence 
Justification 
O Strategy 
0 HiCoal 

£2? Patterns 
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Editing Metadata — Creating Attributes and Parameters 

An attribute must already exist for it to be added to a node’s metadata. 

To create an attribute and its parameters to add it to a specific node, 

1 . Follow the same initial steps as for editing an attribute. Right-click the node. Select 
Edit and then Edit Attributes. In the node’s Edit Attributes box, click Add. 

2. If the attribute to be added is not listed in the Attribute Selection box, it must be 
created. Click the Attributes link near the top to open the Preferences box. 

3. In the Preferences box, click Add to create an attribute. 

4. Name the attribute. Choose its parameter types by clicking Add and individually 
selecting parameters from the list in the Type Selection box . Click Add to add each 
parameter to the attribute. Click OK to add the attribute to the Attributes list in the 
Preferences box. 

5. In the Preferences box, click Apply and OK. The newly created attribute should 
appear in the Attributes Selection box. 

6. Select the attribute to add, click OK, and in the Edit Attributes box, select the 
attribute parameters and click OK. 

7. Click OK in the node’s Edit Attributes box. The new attribute should appear in the 
node’s metadata. 

See the following example for creating an attribute and determining its parameters. 


AdvoCATE User Guide 


39 


Example: Editing Metadata — Creating Attributes and Parameters 


An attribute must already exist 
for it to be added to a node’s 
metadata. 

To create an attribute and its 
parameters to add it to a 
specific node, first select the 
node and go to Edit Attributes. 
In this case, risk does not 
appear in the Attributes 
Selection list, so it must be 
created . 

1 . Select the Attributes link in 
the in Attribute Selection 
box. This opens the 
Preferences box. 

2. In the Preferences box, 
click Add. 


f* n 


Attribute Selection 


Attributes are defined on the Attributes preference page, 
Select an attribute: 

© req u ire m en E(Le ve I ) 

© auto -gene rated 
® hazard(String) 

© formaJizesCModeld} 

® formalizedBytNodeld^ 

® formal 

® usesAssumption(Nodeld) 

® usesRequirementdSsodeJd) 

® verified Gy (String) 

® specified I n(Stnng) 

© has Param (String) 

© hasParam (String, String) 



Cancel 


] L 


OK 


Preferences 


type filter text 


► General 
▼Advocate 

► Build 
▼ Editor 

Attributes 

Enumerations 

Styles 

► Formal Tools 

► Data Management 

► Run/Debug 

► Team 


Attributes 

' T T 


Add, edit or remove attributes. 



® reqtiirement(Level) 

I Add,.. I 


® auto -gene rated 



® hazard(String) 

® formalizes(Wodeld} 

© formalizedBy(Nodeld) 

® formal 

® usesAssumption{Nodeld) 
® usesRequirement(3s!odeld) 
® verifiedfiy(String} 

® specified ln(String) 

® hasParam (String) 

® hasParam (String, String} 



Remove 


Restore Defaults | | Apply- 
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Example (cont.): Editing Metadata 

Parameters 

3. Name the new attribute — 
in this case, “risk”. Click 
Add to open the 
parameter Type Selection 
box. 

4. In the Type Selection 
box, choose each 
parameter — Likelihood 
and Severity — and click 
Add to add each one to 
the list of parameters in 
the Add Attribute box. 


Creating Attributes and 



© O Type Selection 

Select a parameter type 

T String 
T Integer 
T NaturalNumber 
T Nodeld 

0 Level { tiigh-tevel, low-ievel } 

© Severity ] catastrophic, hazardous, majoir minor ] 

© Likelihood { probable, remote, extremely -re mote, extremely 


(?j ^ Gance) I | OK 
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Example (cont.): Editing Metadata — Creating Attributes and 
Parameters 


5. When all 
parameters 
have been 
added to the 
Add Attribute 
list, click OK. 


Add Attribute 


Name: 


risk 


Parameters. 

© Severity { catastrophic, hazardous, major, minor } 

G Likelihood { probable, remote,, extremely -re mote, extremely-i ... 

Remove 


Move Up 


Move Down 
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Example (cont.): Editing Metadata — Creating Attributes and 
Parameters 

6. Risk now appears in 
the Attribute Selection 
list. Select Risk and 
click OK. 

7. In the Edit Attributes 
box, make the 
appropriate parameter 
selections. At this 
stage, enter the 
parameter 
characteristics (e.g. 

“catastrophic” for the 
Severity parameter) if 
they do not already 
exist. Click OK. 

8. Click OK in the node’s 
Edit Attributes box to 
add the risk attribute 
to the node’s 
metadata. 


_ _ _ Attribute. Selection 

Attributes are defined on the Attributes preference page. 
5elect an attribute: 

® reqiiEremenE(LevelJ 
® auto-generated 
@ hazard(String) 

® fo rmaili zested eld > 

© formaiizedBy(Nodeld) 

@ formal 

® usesAssumption-USodetd) 

® uses Re quirem entered eld) 

® verifiiedEy(String] 

® specifi ed1n(String} 

® has Pararn (String) 

® hasParam (String, String) 

® hsk(Severity, Likelihood) 

(D ! Cancel | | QK 

6 
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Editing Metadata — Adding Existing Attributes 


• i 
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■ ktehrdl r 

' InEonlnitOi 
' li.Unh 

m «#*» 

— ! LihF 
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Save n Pallcrn 
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O Attribute Rejection 

Attributes are defined on the Attributes preference page, 
Select an attribute: 

® req u ire m e n t(Le ve I ) 

® hazardf String) 

® riskdlkelihood, Severity) 

@ formalizes (Nod eld) 

© formal izedEy(Nodeld) 

® formal 

® usesAssumption(NodeFd) 

® usesRequirement(Nodeld) 

® vertfiedBy (String) 

@ specified 1n(5tring) 


@ 3 Cancel | | DK | 


Metadata comprises 
attributes, which in turn are 
can contain parameters. 

To add an attribute from the 
library, 

1 . Right-click on the node. 
From the drop-down 
menu, select Edit > Edit 
Attributes. 

2. In the Edit Attributes box, 
click Add. 

3. In the Attributes Selection 
box, select the attribute to 
add and click OK. The 
added attribute should 
appear in the node’s Edit 
Attributes box. Click OK. 

The attribute will appear in the 
metadata field of the node’s 
Properties panel. 
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Example: Editing Metadata — Adding Existing Attributes 



0 •argument-demo S3 
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System A ts 
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O 1 Undo connection creation 
(jjjj-j Print- 
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Paste 
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Verify By... 

Add Node 
Change Node Type 
Show/Hide... 
Hierarchy 
Save as Pattern 

Export Diagram... 
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Q[ Edit Attributes 
Edit Hyperlinks 


3€0 


I 



Attributes: 


Edit Attributes (Coal Cl) 


I Add— | 


Edit... 


Re move 


2 
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e o Attribute Selection 

Attributes are defined on the Attributes preference page, 
Select an attribute: 

@ requirement(Level) 

® hazard£5tring) 

® risk(Likelihood, Severity) 

® formaiizesCNodeid} 

® formalizedByCNodeld) 

@ formall 

@ usesAssumptionJNodefd) 

® usesRequirement(Node3d) 

@ verifiedBytString} 

® specified In(Stnng) 


® I Cancel | | OH 


For example, to add 
Risk as an attribute to 
the G1 node, 

1. Select G1. Click 
Edit and then Edit 
Attributes. 

2. The node’s Edit 
Attributes box 
should be empty 
because there are 
no attributes 
associated with 
this node. To add, 
an attribute, click 
Add. 

3. Select Risk from 
the list of 
attributes. The 
attribute 
parameters for 
risk are Likelihood 
and Severity. 

Click OK. 
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Example (cont.): Editing Metadata — Adding Existing Attributes 


Edit Attribute 


® ris k(Li kelih ood , Seve rity) 


Likeiibood 

[ probable 

-1 




Severity 

| catastrophic 

i 1 


4 ® 


Cancel _| |_ OK 


& Edit Attributes {Coai Gl} 


|~ Add... | 

Edit... | 


Remove 


5 ® I Cancel | I OK ) 


Attributes: 

® nsk(probable, catastrophic) 


4. 


5. 
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Problems I [H3 Properties £3 

M 


l>)= Parameters ,/ Search 


^ a □ 


- Properties 

Identifier: Cl 

Description: System A is acceptably safe 

Metadata: hs Improbable, catastrophic) 

Comment: 

Hyperlinks: 

Cl To Be Instantiated 
To Be Developed 
0 Public 


6. 


In the Edit Attribute box, 
specify the attribute 
parameters with the 
dropdown menus. In this 
example, the parameters of 
Likelihood and Severity are 
characterized as probably 
and catastrophic, 
respectively. Click OK. 

The risk attribute should now 
appear in the node’s Edit 
Attributes with the specified 
parameters. Click OK. 

The risk attribute now 
appears in the node’s 
metadata field in the 
Properties panel. 
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Adding Attributes Directly to the Library 


Attributes do not have to be created 

only when editing a node’s metadata. 

Add an attribute to the library by: 

1 . Selecting Preferences from the 
AdvoCATE tool menu. 

2. From the Preferences box, follow 
the steps as for adding an 
attribute to a node. 

a. Name the attribute and select its 
parameters. In the Add Attribute 
box, click OK. 

b. The new attribute should appear 
in the Attributes list of the 
Preferences box. Click OK to 
close. 


File Edit 
About AdvoCATE 

Preferences... EH!, 
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► Run /Debug 
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► Team 
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® usesRequirement(Nodead) 




® verified Ey(String) 




® specified ln(String> 




® hasParam(5tnng) 




® hasParamCString, String) 



| Restore Defaults j 

1 Apply | 


@ I Cancel | I OK | 
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Parameter Type ID: SameNodeTypeld 


e o 


Attribute Selection 


Attributes are defined on the Attributes preference page, 
Select an attribute: 


/ 


® formal 


'O. tonmallzes(SameNQdeT' peld) 


® formaiizedEy(5ameNc^eType!d) 

® hazard(Hazardld) / 

® requirenientCTier} 

® riskdikelihoods Severity) 

® specified in(Stnng) 

® u ses A 5 s li m pti on (Ass u m pti on N o de I d ) 
® usesRequirement(Coa!Mode1d] 

® ve ri fied EyCT o o I N am e) 



Cancel | | OK 


Each parameter contains an ID that 
indicates something about which 
nodes it can be assigned to. Add the 
SameNodeTypeld attribute to a node 
to represent relationships between 
nodes of the same type. 

For example, select a goal node, and edit its 
attributes. Click Add. In the Attribute box, 
select and add an attribute with 
(SameNodeTypelD) as its ID. Click OK. 



In the Edit Attribute box, notice that this 
particular attribute ID is specific to goal 
nodes only — because that is the node type 
this attribute is assigned to. 
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Parameter Type ID: SameNodeTypeld (cont.) 



Edit Attributes {Coai G1J 


Add... 




Remove 


Attributes: 



Continuing this example, select a 
node from the list (in this case, 
goals) and click OK. 

The attribute should appear in the Edit 
Attributes box. Notice that the attribute 
ID is the node specified during the 
previous step (G2). Click OK. 

The attribute now appears in the 
metadata field of the G1 node’s 
properties. 



_ Cancel | | OK 
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Attribute Type: Synonyms 


e o 


Preferences 


type fitter text 


► General 
▼ Advocate 
► Build 
▼ Editor 

▼ Attributes 

Enumerations 


Synonyms 


Styles 

► Formal Tools 
Data Management 

► Run /Debug 

► Team 


Synonyms 


\P ’ 


Add, edit or remove synonyms. 



Cancel 


:i c 


OK 



/ 


Most of the Attributes covered so far 
have contained editable 
enumerations (e.g. likelihood, 
severity, etc.) but another attribute 
type is the Synonym. 

To add/remove/edit synonyms: 

1 . Navigate to the Attributes preferences 
box 

2. Under Attributes, select Synonyms 

3. Click on an existing Synonym to edit or 
remove it OR click Add to create a new 
one. Enter the name of the new 
Synonym and click OK. It will 
appearance in the list of Synonyms in 
the Preferences box. 

For example, to add a Synonym called 
formalLanguage, click Add in the 
Preferences box, type in formalLanguage 
and specify the Synonym type (here, it is 
“string”) and click OK. 
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Editing Properties: Adding Hyperlinks to Nodes 


Adding a hyperlink to a 
node is another way to 
edit its properties. 

The method of adding 
hyperlinks directly to a 
node is similar to 
adding attributes. 

1 . Right-click to select 
the node. From the 
menu, select Edit 
and then Edit 
Hyperlinks. 

2. In the node’s Edit 
Hyperlinks box, 
add a hyperlink by 
clicking Add. 
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Add Hyperlink 





Browse Project... 

j =j Browse Workspace... 

Browse File System... 



Witching resources: 

D -project 

argument -demo. argument 


Select a resource to open [7 = any character, * = any string). 


Editing Properties: Adding Hyperlinks to Nodes 

3. Add a hyperlink from multiple ^ 

sources. Hyperlink: 

a. Click Browse Projects to 
link to an existing project 
resource or folder. In the 
search box, specify the 

search terms in either the _* n_ 

Resources field or by 
clicking among the fold 
Click OK. 

b. Click Browse Workspace\o 
link to an existing 
workspace resource or 
folder. In the search box, 
specify the search terms in 
either the Resources field 
or by clicking among the 
folders. Click OK. 

c. Click Browse File System to 
link to local files. Select a 
file and click OK. 

d. Type in a Web URL directly 
into the hyperlink field. 

Click OK to close the Add Hyperlink 
box. 


Cancel 


OK 



In this example, the user clicked 
Browse Project. In the search box, 
the user typed * to show any string of 
resources and folders associated 
with that project. The user selected a 
resource and clicked OK to close the 
search box. The resource hyperlink 
appeared in the Hyperlink link field of 
the Add Hyperlink Box. 


Add Hyperlink 


Hype rl jfi k: hie:// 5{ work spacej oc : /arg u m e n t- de m o / ar g u m e nt- d emo ,arg a me nt} 


Browse Project,. 
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Browse File System. 


Cancel 
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Editing Properties: Adding Hyperlinks to Nodes 

4. 


Click OK to 
close the Edit 
Hyperlinks box. 
The hyperlink 
should now 
appear in two 
places: in the 
Hyperlinks field 
in the node’s 
Properties panel 
and as a globe 
icon when 
hovering over 
the node. 
Clicking the 
globe icon will 
open up a 
dialogue box to 
select a link to 
navigate to. 
Some hyperlink 
files will open as 
a separate tab. 


BOO Advocate - p latform : / reso lj rce/argumen t- d e m o /argum e nt-rfe mo . argu merit#/ 0 - AdvoCATE - /Users /vjphil la/ Desktop/ advocate 2/advocate.app, .. 
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Palette 
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Editing Properties: Editing/Viewing/Removing Hyperlinks to Nodes 


Once a hyperlink has 
been added to a node, 
it can be edited, 
removed, or viewed in 

O r ~ Edit Hyperlinks (Assumption Al) a separate project tab. 

To edit a hyperlink, 
select the hyperlink 
within the node’s Edit 
Hyperlinks box, and click 
Edit. 

To delete a hyperlink, 
select the hyperlink 
within the node’s Edit 
Hyperlinks box, and click 
Remove. 

To view the hyperlink in 
the separate project tab, 
select the hyperlink 
within the node’s Edit 
Hyperlinks box and click 
View. 


HyperFmks: 


% fi If*:// 5 fworkspacoj oc: / argu menl-de mo / arg u m eirt-demo. argu me n t} 


Add.,. 


Edit,.* 


Remove 


| View.. 


Cancel I [ OK 
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Selective Views 


Selective views provide queries of hiding / showing specific views so as to manage argument structure complexity 


■ Advocate - platform:/resource/test-pro)ect/argunient-0.acd#/0 -AdvoCATE 




File Edit View Navigate Search Project Run Window Help 

I r: - y ® m I I -y 


Project Explorer S2 
t> 1 gbsaa-sc 
d £? test-project 

dl argument-0, acd 
dl argument- 0 -G 5 .acd 
d \B test-project-2 

El ehdb-pattern.acp 
E] ha-pattem.acp 


O ’ : ' I I I I - I + . 100% - 

0 ^ ^ “ □ d| ’argument-0 £3 d) argument-0— G5 


Ef | [~tS Advocate 1 


To invoke selective 
views, select a node, 
and access the 
Show/Hide option in 
the right-click menu 




Problems ^ Tasi: 0 Properties 

Base 

*■ Properties 


Hide this node and subnodes 
Hide subnodes 
Show path to this node 
Show subnodes 
Show all nodes/loops 


SI 


Identifier: 

Description: Argument of compliance with regulations 
Attributes: 


Blue 


Comment: 

Color: 

Uris: 

Variables 

□ To Be Instantiated 
OTo Be Developed 


v> Palette 


Select 
[4 Marquee 


Connections <0 
—* IsSolvedBy 
InContextOf 
~ * HiLink 


& Objects o 

[=>Goal 
® Assumption 
l= J Context 
O Evidence 
O Justification 
O Strategy 
E 3 AwayGoal 
Q AwayContext 
^ AwaySolution 
□ HiNode 


& Patterns 
ehdb-pattem 
ha-pattern 




Five views 
are currently 
available 
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Selective Views 


On selecting a view, a node or its parent, as appropriate, is decorated to indicate that the view includes hidden structures 


■ Advocate - platform :/resource/test-proJect/argument-0.acd#/0 - AdvoCATE 


i°is» 


File Edit View Navigate Search Project Run Window Help 

^3 Project Explorer £3 
> £3 gbsaa-sc 
* £3 test-project 

Hi argument-O. acd 
Hi argument-0-G5.acd 
d £3 test-project-2 

0 ehdb-pattem.acp 
0 ha-pattem.acp 


Node decoration 
to indicate that 
there is an 
attached hidden 
structure. 



| Q, Q, 100% - 


HR Problems v_i Tasks □ Properties S3 S Console 


J 


Miniature View S3 



* Properties 


Node : 


(8 | [ B Advocate! 

° □ 







r C1 'N 

I X/ Definition of j 





"acceptably safe” J 
























































& Connections 

* IsSolvedBy 

* InContextOf 
*HiUnk 


1^ Select 
Marquee 


£3 Objects o 

1=1 Goal 
® Assumption 
=* Context 
O Evidence 

^Justification 
O Strategy 
B AwayGoal 
Q AwayContext 
0 AwaySolution 
□ HiNode 


& Patterns 
ehdb-pattern 
ha-pattem 


^ □ 


ESS® 


♦ Goal G1 

♦ Strategy SI 
•♦■Assumption A1 
♦■ Justification J1 

♦ Context Cl 

♦ Goal G2 


Link : 




♦ Is Solved By Is Solved By 

♦ In Context Of In Context Of 

♦ In Context Of In Context Of 
4- In Context Of In Context Of 

♦ Is Solved By Is Solved By 


To show a hidden 

structure: 

1 . select the decorated 
node, 

2. access the 
show/hide option 
from the right-click 
menu 

3. select the 
appropriate view 
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Search 

To search for 
keywords appearing in 
the project's text, 
open the Search 
dialogue box by 
selecting the Search 
tab in the application 
toolbar (or using the 
keyboard shortcut). 
Within the Search 
dialogue box, choose 
to search within the 
AdvoCATE application 
or within local files by 

1. Clicking the 
Customize button 
at the bottom left 
of the dialogue 
box and choosing 
an Advocate 
Search or local 
File Search OR 

2. Selecting either 
tab at the top of 
the box. 


J0 ■ 4dvqGATE - 


Sa 'arffumcnH-dcm!? S3 


a 



4 

Mii^bPf 

Son run tom 

^ Inf iml-rj&Hf 
HI Lank 
l 

Izl^i 

Gwitoi! 

■Q fortune* 

£ 7 Stmpfjf 
IJMltDAi 
y~\ HiFnidrmi; 
HIEurMEflv 


•J? ^ 


Cum i 




1 JVabiMn 63 PtopirtiEi K (*» r±urrrlEF-k ■ jeinti ** & O 

PfMlriptN^' 

<■ -SirJUflv 5T 
t t«-ti C I 
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Search in AdvoCATE 


Limit the scope of the 

AdvoCATE search by: 

• Limiting the search to 
specific node types by 
checking the appropriate 
boxes under Node in the 
search dialogue box. 

• Limiting the search to 
specific fields within the 
node parameters by 
checking the appropriate 
boxes under Field in the 
search dialogue box. 

• Defining the scope of the 
search to be within the 

• The Workspace 

• Selected Resources 

• Enclosing Projects 

• Defined Working Sets 



Node: 

10 Assumption 
0 Context 
0 Evidence 
0 Coal 
0 Justification 

B D 


0 Description 
0 Metadata 
10 Comment 
0 Links 

B □ 


Scope 

* Workspace 
Working set 


Selected resources 


1 Enclosing projects 


Customize.,, 


Cance; 


Search 


Enter Search terms here 


Narrow the Search to specific 
node types by checking the 
boxes besides each Node 


Narrow the Search to specific 
node parameters by checking 
the boxes besides each Field 


Define the Scope of the search 


One the search terms have 
been entered, click Search. 
Search results will appear in the 
Search panel below the canvas. 
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Search in Files 


Limit the scope of the File 

search by: 

• Limiting the search to 
specific File name patterns. 
Separate terms with 
commas. 

• Limiting the search to 
specific file extensions by 
clicking Choose and 
selecting the appropriate 
file extension type. 

• Defining the scope of the 
search to be within the 

• The Workspace 

• Selected Resources 

• Enclosing Projects 

• Defined Working Sets 


e o 


Containing text: 


Search 


./ Advocate Search 




Case sensitive 

(* = any string, 7 = any character, \ = escape for literals: * ? \) 

Regular expressron 
■ Whole word 

File name, patterns (separated by comma): _ 


I* A, 

| Choose... | 

(* = any string, 7 = any character. !x = excluding x) 
Consider derived resources 


Scope 



* Workspace Selected resources 

Working set 


Enter Search terms here 


Enter terms here to search 
through File name patterns 


Choose which file extensions to 
search through 


Choose.,. 


Define the Scope of the search 


(jf) Customize.,... 


| Replace... | Cancel [ Search | 


One the search terms have 
been entered, click Search. 
Search results will appear in the 
Search panel below the canvas. 
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Structuring Arguments 
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Associated Diagrams 

• Associated diagrams manage argument 
structure complexity by splitting a 
structure across multiple canvases. 

• An association connects source nodes 
to target nodes through an association 
property within the nodes’ Properties. 

- The target node will show a Continued- 
from association. 

- The source node will show a 
Developed-elsewhere association. 
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Example: Associated Diagrams between Existing and New 
Arguments 


To create an association 
between an existing 
source node and new 
target node, 

1 . Select the source node 
and, in its Properties, 
click the Association 
drop-down menu and 
select “Developed- 
elsewhere”. A green box 
will appear in the lower 
left of the node. 

2. An Associated Argument 
Selection box will 
appear with a field to 
search through existing 
arguments with that 
node name and type. If 
none exist, click <New> 
and then OK. 


I^j ’Modulel ,i_i 'Module! [£j ’Modules |^| ^contract! [£| “argument 1 



























Goal 
















































□_ Problems yj, Tasks EH Properties £3 § Console (*)= Parameters 


Goal 


▼ Properties 
Identifier 
Description: 

Metadata: 

Comment: 

Hyperlinks: 

To Be Instantiated 
To Be Developed 

L' Public 

) Be Supported By Contract 
/ 

Associated ArgilTHent: 


To t 


Associarf 


Continued -from 


Bevel oped -elsewhe re 


Cancel | OK | 
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[§] ‘Module! [§) *Module2 *Module3 [£j ‘contract! [§) ‘argument 1 [5) ‘argumentZ 


Example (cont.): Associated Diagrams between Existing and New 
Arguments 

3. Select the project in 
which to create the 
target node and name 
the target argument. 

Click Finish. 

• The new node should 
now show a green box 
on the upper right, 
indicating that it is 
associated with another 
node. The node’s 
Properties indicate that 
it is “Continued-from” 
another node. 





















1 




1 

Goal 




































Problems Tasks [_j Property 


0 Co n sol e [*)= Para m e te r s 


T Properties 

Coal 

description: 

Metadata: 

Comment: 

Hyperlinks: 

► Be Instantiated 
Developed 

Public 

To Be Sup port^N^y Contract 
Association. Continued-from 

Associated Argument: 
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Example (cont.): Associated Diagrams between Existing and New 
Arguments 


• Clicking the icon on 
the upper right of 
either node will direct 
to to its associated 
counterpoint. 



I Open Associated Argument 

Open argument^} associated with this goal 
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Example: Associated Diagrams between Two Existing Arguments 


tej "Module! in 'ModuleZ [isj # Module3 g ‘contract! [5) “argument! £3 


To create an association between an 
existing source node and an existing 
target node, 

1 . Create two nodes of the same name, 
one in each of two arguments. For 
example, G1 in argumentl .argument 
and G1 in argument2. argument. 

2. Select the source node and, in its 
Properties, click the Association drop- 
down menu and select “Developed- 
elsewhere”. A green box will appear in 
the lower left of the node. 

3. An Associated Argument Selection box 
will appear with a field to search through 
existing arguments with that node name 
and type. Select the appropriate 
argument (in this example, 
argument2. argument and click OK. 




















Goal 














































§1 Problems ^ Tasks EH Properties £3 

H3 Console (*)= Parameters 


^ Properties 
Identifier 
Description: 
Metadata: 
Comment: 


Goal 


Hyperfinks: 

To Be Instantiated 
To Be Developed 
Q Public 

To Be Supported By Contract 
Association: / 

dated Argument: 


Continued -from 


Devel op&d -elsewhe re 


Associated Argument Selection 


Select an associated argument (? = any character, * = any string): 

- 

0 

0 ) 

Matching items: 

|1 : ; <New> 


i) argument2.argument 




l °* I 
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0 'Modulel 

[2] *Module2 [2) *Module3 [2) 'contractl [2] 'argument 1 [2] *argument2 £2 










1 

cSs — a 


















Example: Associated Diagrams between Two Existing Arguments 
(cont.) 

4. AdvoCATE will 

automatically open the 
target argument’s 
canvas. In the 
Association drop-down 
menu of the target 
node’s Properties, 
select “Continued-from”. 

The node should now 
show a green box on 
the upper right, 
indicating that it is 
associated with another 
node. 

• Clicking the icon on the 
upper right of either node 
will direct to to its 
associated counterpoint. 


fi Problems ^ Tasks □ Properties S3 S Console W= Parameters 

T Properties 
Identifier 
Description: 

Metadata; 

Comment. 

Hyperlinks: 

Be instantiated 
levc-iQped 

G Public 

To Be Sup p or on tract 

Association: | Can tinued-from 

Associated Argument: 


1 

1 

di^. 

1 1 





1 

— i 

II 

1 

□ pen Associated Argument 

□pen argument^} associated with this goal 





r n 

fw 1" 
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Hierarchy 


Another method to reduce a diagram’s complexity is to employ Hierarchy to 
create a recursive group of meaningful subsets of the argument structure. 

To add hierarchy: 

1 . Select the root node. Optionally, select additional nodes to include in the 
hierarchy structure. Right-click on the root node. 

2. Select Hierarchy-^ Create Hierarchical Node 


Hierarchy 
currently 
cannot be 
applied to 
patterns or 
modules. 


[§j "Modulel [§) *ModuleZ |§) T Module 3 [£] "contractl [tj "argument 1 [£] ‘arguments [§ T Module4 £3 


C Undo connection creation 
i^, Print... 



Update 

Delete 

Layout 

Edit... 

Add Node 
Change Node Type 
Show/Hicfe... 


Hierarchy 


Save a5 Pattern 
Export Diagram... 


□ F5 


► 

► 

► 

► 


= 

□ 

0 Palette 

» 

Select 


Marquee 


(^Connections 

CO 

* IsSolvedBy 


“ r> InContextQf 


HiLink 


& Objects 

CO 

CH Coal 


® Assumption 


— 1 Context 


Q Evidence 


1 ^'Justification 


LJ Strategy 


|H| AwayGoal 


j |AwayContext 


|— j AwaySolution 


i 1 . . i t - * 





Create Hierarchical Node 


Open/Close Hierarchy 
Calculate Hierarchy 
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Creating Hierarchy 

The structure undergoes 
auto-layout whenever a 
hierarchical node (hinode) is 
created. 

AdvoCATE currently 
computes three kinds of 
hinodes, subject to certain 
conditions: 

• hierarchical goals 
(higoals), annotated as G 

• hierarchical strategies 
annotated as S 

• hierarchical evidence 
annotated as E 


[£] *Modulel [5) *Module2 @ *Module3 [5) *contractl @ *argumerttl g *argumerrtZ [£] *Module4 U 



The hinode type is 
determined by the nodes 
contained within the 
hierarchical structure. 
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Example: Creating Hierarchical Structures 

The next several slides will walk through 
creating hierarchical goals, strategies, and 
evidence structures based on the complex 
diagram at right. 




Note that the rectangles are goal nodes, the 
oblong shapes are context nodes, the ovals 
are justification nodes, the circles are 
evidence nodes, and the parallelograms are 
strategy nodes. 

At each step you select the root of the 

fragment which will be turned 

into a hinode and, optionally, the nodes that 

come just after thefragment to be included 

in the hierarchy (the delimiting nodes). 

Multiple nodes can be selected using 

Command-click. 
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Example: Creating Hierarchical Goals 


To create a 

hierarchical goal, 

1. Select G1 as the 
root node. 

2. Select S3 and 
S2 as the 
delimiting nodes 
for the hierarchy. 

3. Right-click on the 
root node. Select 
Hierarchy-^ 
Create 
Hierarchical 
Node 


Root node: 
Goal 






c 

1 n t 














C 

1 

j - Dr 

f 

O' Undo Delete HiNode 

1 














/ 

Print- 













* 

/ 

Copy 

Paste 












co > 

Alignment ► 

Update 3£fs 

Remove OEx> 













/ 













j 

/ 

Delete 

Layout 

Edit... ► 

Formalize 













GZ 

~\ 












/ 

' \ 

\ 

Verify By... ► 

Add Node ► 










□ 

.. JX, 

/ 

1 


Change Node Type ► 

Show/Hide... ► 








□ 

A 

r f u 

1 

1 

;/ 

Hierarchy ► 

Create Hierarchlca 

1 Node 



Save as Pattern 

Queries ► 

Open/Close Hierarchy 
Calculate Hierarchy 

f n- -i T — 

Cr* 

/ 

' 

u 

\ 

\ 

/ 

m 

\ 


\ 

Export Diagram... 3£0 

r 









1 


CB 

\ 

V 











Delimiting nodes 
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Example: Creating Hierarchical Goals 


The selected 
area is 

condensed into 
a hierarchy, 
leaving the rest 
of the original 
diagram intact. 



Hierarchical 

Goal 
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Root node 
Strategy 


Example 1: Creating Hierarchical Strategies 


To create a 
hierarchical 
strategy structure, 

1 . Select S2 as 
the root node. 

2. Select G4 and 
G6 as the 
delimiting 
nodes for the 
hierarchy. 

3. Right-click on 
the root node. 
Select 
Hierarchy-^ 
Create 
Hierarchical 
Node 



□ 

□ 

□ 





Copy 

Paste 

Alignment 

Update 

Re m ove 

Delete 

Layout 

Edit... 

Formalize 
Verify By... 

Add Node 
Change Node Type 
Show/Hide... 


Hierarchy 


Save as Pattern 
Queries 


► 

38 FS 

► 

► 

► 

► 

► 


► Create Hierarchical Node 

► 

Open/Close Hierarchy 
Calculate Hierarchy 

' 



Export Diagram... 380 
























Delimiting 

nodes 
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Example 1: Creating Hierarchical Strategies 


The selected 
area is 

condensed into 
a hierarchy, 
leaving the rest 
of the original 
diagram intact. 


Hierarchical 

Strategy 
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Example 2: Creating Hierarchical Strategies Structures 


To create another 
hierarchical 
strategy structure, 

1 . Select S5 as 
the root node. 

2. Select G8 as 
the delimiting 
node for the 
hierarchy. 

3. Right-click on 
the root node. 
Select 
Hierarchy-^ 
Create 
Hierarchical 
Node 











Z 7 


/ 


7 


t 1 

t 


<£? Undo Delete HiNode 
q Print... 

Copy 

Paste 

Alignment ► 

Update 3 £f5 

Remove OK> 

Delete 

Layout 

Edit... ► 

Formalize 

Verify By... ► 

Add Node ► 

Change Node Type ► 

Show/Hide... ► 


Hierarchy 


Save as Pattern 

Queries ► 

Export Diagram... 3SO 

— i 1 1 


Root node: 
Strategy 


Create Hierarchical Node 


Open/Close hierarchy 
Calculate Hierarchy 
|l " J T * =x ?= 


Delimiting 

nodes 
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Example: Creating Hierarchical Evidence 


To create another 
hierarchical 
evidence structure, 

1 . Select S3 as 
the root node. 

2. Right-click on 
the root node. 
Select 
Hierarchy-^ 
Create 
Hierarchical 
Node 


Note that because 
no delimiting nodes 
were selected, the 
hierarchy will 
include all nodes 
down to the leaf 
nodes. 



< 


Root node: 
Strategy 


i. 



Leaf node: 
Evidence 


Hierarchical 

Evidence 
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Example: Creating Hierarchical Evidence 


The selected area 
is condensed into 
a hierarchy, 
leaving the rest of 
the original 
diagram intact. 


Hierarchical 

Evidence 
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Example: Creating Nesting Hierarchies 


^ j 


Outer 

Hierarchy 


C ;! Undo Create Hierarchical Node 

Print... 

Copy 

Paste 

Update 

Remove 
Delete 
Layout 
Edit... 

Formalize 
Verify By... 

Add Node 
Change Node Type 
Show/Hide... 


Hierarchy 


3EF5 


► 

► 

► 

► 


Save as Pattern 
Queries 


Properties So. Export Diagram... 


msmmmm 

Qpen/Close Hierarchy 
► Calculate Hierarchy 

ma 

able Preview f§ Verification 


Hierarchical Goal 
nested within a 
Hierarchical Evidence 
Structure 


To create nested 
hierarchical structures (a 
hierarchy within a 
hierarchy): 

1. Within a hierarchy, 
select the a root node 
for the inner hierarchy. 

2. Right-click on the root 
node. Select Hierarchy-^ 
Create Hierarchical Node 




G nr.: 




3 

r 

" 


4 
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Opening/Closing Hierarchies 

Hinodes can be closed/opened to collapse/expand the argument structure. 



Hinodes have a 
default Open status 
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Opening/Closing Hierarchies 

Closing a hinode collapses the node, improving visual comprehension by hiding its internal structure 


■ Advocate - platform:/resource/test-proJect/argument-0.acd#/0 - AdvoCATE 





[ CU 1 ® 

File Edit View Navigate Search Project Run Window Help 

t ~ ^ w \ * I 1 

mrn 1 5 * ?p| c 

i4 n fo □*. 

?| .. id: 1 1 ^ si 80 % - 

Quick Access 

| [ B Advocate 1 


[£3 Project Explorer S3 
t> £3 gbsaa-sc 
a £3 test-project 

H argument-O.acd 
Hi argument-0-G5.acd 
> £3 test-project-2 


B % 


H *argument-0 S3 



J S2 / 










Argument 0 
hazard 
mitigation , 
























r 












[2_ Problems ^j] Tasks □ Properties ' 


Miniature View S3 































r 

















G8 

Failure hazard of component, 
in operating phase 1 is 
















mitigated 











O 






















Palette 


Select 
[ j Marquee 


& Connections <0 
IsSolvedBy 
InContextOf 
HiLink 


& Objects <0 

□ Goal 

® Assumption 

□ Context 
O Evidence 
^ Justification 
O Strategy 
P AwayGoal 
Q AwayContext 
0 AwaySolution 
BHiNode 


& Patterns 
ehdb-pattem 
ha-pattem 


1 

* 



▼ Properties 




Identifier: 

HI 


= 

Description: 

Argument by decomposition over architectural breakdown and operating phases 



Attributes: 




Comment: 




Color: 

| Green — ■ — 

*1 


Uris: 




Variables: 




O To Be Instantiated 


Status: 

[ Closed 

•I 





' r 


Hinodes status is 
updated to Closed 
on closing the 
hierarchy 
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Example: Closing a Hierarchy 


Closing a hierarchy will 
minimize the hierarchical 
structure, preserving the 
internal nodes. 

To close the hierarchy, 

1. Click on the 
hierarchy. 

2. Select Hierarchy-^ 
Close Hierarchy. In 
the hierarchy 
Properties, the status 
will indicate that the 
hierarchy is Closed. 

Deleting the hierarchy will 
delete the hierarchical 
structure but not its 
contents. However, 
selecting Delete HiNode 
Contents will delete the 
nodes contained within 
the hierarchy. 



O' Undo connection creation 
1^3 Print- 


Update 3 €f5 

Delete 

Layout 

Edit... ► 

Delete HiNode Contents 
Add Node ► 

Show/Hide... ► 


Save as Pattern 

Export Diagram... 3€0 


Create Hierarchical Node 

Calculate Hierarchy 
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Calculating Hierarchies 

• Calculating hierarchy screenshot 
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Modules 


Modules prevent complicated diagrams from becoming too unwieldy by 
providing connections between arguments and patterns contained on 
separate canvas tabs. 

The two types of modules are: 

• Safety Case Module 

• Safety Case Module Contract 
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Creating a Module 

To create a module canvas on a new 
tab 

1 . Select File -> New -> Safety 
Case Module 

2. Select the parent folder (usually 
a project) in which to put the 
module 

3. Name the module 

4. Click Finish 


Edit View 

Navigate Search 1 

Project Window help 

1 New 

'C&N ► 

US Advocate Project 
Tj Project... 

Open File... 


Close 

sew 


Close All 

osew 

C3 Folder 

(HI Save 

ses 

Q File 

(sjf' Argument Structure 

Save As... 


Argument Pattern 

Save All 

os«s 

Bf Safety Case Module 



Safety Case Module Contract 

Move- 


Uj Other... 3€N 

Rename... 

¥2 

" 7 

Refresh 

¥3 


m o o 

New Hie 


Safety-Case Module 

Create a safety-case module file resource, 


Enter or select the parent folder: 



Filename: Module l| 

| Advanced >> 


Cancel 
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Creating a Module (cont.) 

Notice that the new module tab contains an empty 
canvas as well as some new node types in the 
palette. 


V Palette |> 

I 

Select 

[’J Marquee 

\>p Connections 
~ * IsSolvedEy 
~ 1 15 InContextOf 


These node types link to goal, context, and 
solution/evidence nodes in other modules or 
arguments: 

• Away Goal 

• Away Context 

• Away Solution 

These node types allow link to other modules or 
module contract references: 

• Module Reference — link to other modules 

• Module Contract Reference — link to other 
module contract references 



HiLink 


1^5? Objects 




□ Coal 
A Assumption 
. ' Context 
O Evidence 


J Justification 
Strategy 
fill AwayGoal 
| _ j AwayContext 
I — | AwaySolution 
P~l ModuleRef 
L“3 ModuleContrac,. 


HHiCoal 
fj HiEvidence 
|£j Hi Strategy 

: l25? Patterns <£> 
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Example: Linking an existing module reference to a new (non 
existing) module 



|tj argumentx 

0 T Modutel S3 


• Add a ModuleRef object by 














dragging and dropping or using 















the shortcut 

Select the ModuleRef object 
and click on the text, which w+l 
display a dropdown menu with 
all existing modules in that 
project 

To link to a new module that has 
not yet been created, select 
<New> 

In the New File dialog box, enter 
the name of the new module. 
(The parent folder will 
automatically default to the 
name of the project.) Click 
Finish. 




















w i 

Ml 











<lslew> 


Module4 

ModuleB 

Module^ 




New Hie 


afety-Case Module 

Create a safety-case module file resource, 


Enter or select the parent folder: 
project* 


project* 


File name: Module^argument 


Advanced >> \ 


Cancel 
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Example (cont.): Linking an existing module reference to a new (non- 
existing) module 


|£] argumentx 0 *Modulel £3 §] 'ModuleZ 0 *Module3 0 *Module4 



□ pen Module 

Open safety-case module 


The ModuleRef object will be 
renamed to the name of the 
target module— in this case, 
Module4. 

To open the target module, click 
on the icon on the upper right 
portion of the ModuleRef object 
and select Open Module. 
Clicking this link will open the 
target Module canvas. 
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Example: Linking an existing module reference to an existing module 


Select the ModuleRef object and 
click on the text, which will display 
a dropdown menu with all existing 
modules in that project. 

Select the target module to link 
that object to. 

The ModuleRef object will be 
renamed to the name of the target 
module — in this case, Module3. 

To open the target module, click on 
the icon on the upper right portion 
of the ModuleRef object and select 
Open Module. Clicking this link will 
open the target Module canvas. 



Module2 

<New> 


Ih] argumentx 0 ‘Modulel £3 |5] *Module2 [§| ‘Module! |§) *Module4 


Modules 


0 


□ pen Module 

Open safety-case module 
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Example: Away Nodes 


Away nodes simplify complicated 
diagrams and link between nodes in 
separate modules, arguments, or 
structures. 

Any target node must be marked 
“public” so that it is viewable when 
linked from other modules. 

Add a node to the canvas — in this 
case, a goal node called Goal 1 — and 
in its Properties, check the Public 
box. Notice the folder icon that 
appears in the top right of the node, 
indicating that it’s “publicly” viewable. 


|HI argument* [£] *Modulel £3 |£| *Module2 [t) *Module3 |t) 'Modu1e4 


Coal 1 


Modular 


; Problems Tasks E Properties £3 S Console te)= Parameters 




"fifadUta4" 



▼ Pjoper'ties 

Identifier: Coal 1 

Description: 

Metadata: 

I 

Comment: 

Hyperlinks: 

To Be Instantiated 
To Be Developed 
I^I Public 

To Be Supported By Contract 
Association: 

Associated Argument: 
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Example (cont.): Away Nodes 


[£) argumentx [£) Modulel [£) Module2 £2 [£) Module3 [2] Module4 [5] contractl 0 pattern 1 [5) argume 


In the source module, add an away 
node — in this case, add an 
AwayGoal to the canvas of 
Module2. This node can be linked to 
any target goal in another module. 

In this example, AG1 will be linked 
to Goal 1 in Modulel. Notice the 
folder icon that appears in the 
bottom rectangle on the AG1 node. 

Click the drop-down menu beside 
the folder icon and select the target 
module to reference (the one that 
the target node is in) 

Click the away node ID and select 
the node to link it to from the drop- 
down menu, which will only display 
target nodes of the same type as 
the source away node that within 
the reference module. 


a£i 

_ 

Modulel ▼ 


Module4 


Module3 


EE5HS1 


<New> 


Coal 1 


Coal 1 


<New> 


J3 





Coal 1 






P | Modulel 
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Creating Module Contracts 


• Module contracts serve as a justification 
for how two modules reference one 
another; rather, how one module makes 
certain assumptions that are supported 
by the guarantees implicit by another 
module. 

• To create a Module Contract, 

1 . Go to File->New-> Safety Case Module 
Contract. 


2 . 

3. 

4. 


Select the parent folder (usually a 
project) in which to put the module. 


Name the module 
Click Finish. 
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Edit View Navigate Search Project Window Help 


Open File,,. 

Gose 
Gose All 

Save 

E. Save As,.. 
Jj£j Save All 
Revert 


ms 

&ms 


G Advocate Project 
Tj Project... 

Q Folder 
[f File 

gf A rg y me n t St r u ct u re 
[f5 Argument Pattern 
dvf Safety Case Module 


r + Safety Case Module Contract 



O O O New File 

Safety-Case Module -Contract 

Create a safety-case module- con tract file resource. 


Enter or select the parent folder: 



File name: contract, argument 



vanced 




Creating Module Contracts (cont.) 

As with creating modules, notice that the new 
module tab contains an empty canvas as well as 
some new node types in the palette. 

These objects allows linkages between nodes in 
other modules, arguments, or structures: 


%} Palette |> 

Select 

["J Marquee 

(2^ Connections 
* IsSolvedBy 
InContextOf 
^ HiLink 

Objects 


AwayGoal 

AwayContext 

AwaySolution 


This object allow linkages between other 
modules: 

• ModuleRef 


Notice that when creating a module contract 
diagram, other module contracts cannot be 
referenced. 


□ Coal 
* Assumption 
Context 
(_) Evidence 
.“^Justification 
Lj Strategy 
[□ AwayGoal 
I j AwayContext 
i— i AwaySoEution 
□ ModuleRef 
[jpj HiCoal 
e j HiEvidence 
s' J Hi Strategy 
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Example: Using Module Contracts in Diagrams 


• Like Modules, Module 
Contracts can be used to 
simplify complicated 
diagrams. 

• The Module Contract 
Reference object acts as a 
placeholder for Module 
Contracts within other 
modules. 

• See the example at right, 
illustrating the 
relationships between 
several Modules and 
Module Contracts with 
Module or Module 
Contract reference objects. 


[£] *Modulel [5] *Module2 [5] *Module3 [5] *comractl 









1 



Mbdulel 











— i 



contra cil 















1 -- 

Nfodu \ b 2 

1 

i ■ 1 

i 


AdvoCATE User Guide 


93 


Example: Using Away Nodes in Module Contracts 


3 . 


An away node may feature 
outgoing links within a 
module contract 

For example, to create an 
Away Goal, 

Drag and drop the Away 
Goal object from the 
palette onto the canvas (or 
use the shortcut). 

Drag and drop the Goal 
object from the palette onto 
the canvas (or use the 
shortcut). Add a link 
between the nodes. 

Within the Goal node's 
Properties, check the box 
“To Be Supported by 
Contract”. Notice that a 
module contract reference 
icon appears below the 
Goal node. 


© 


AC1 


E=i 


§] argument* [5) ‘Module! @ ‘Module 2 [§) * Modules @ ‘contract 1 £3 


Cl 
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Putting it All Together: Complex Diagram Walkthrough 


Here is an example of a more complex diagram by a hypothetical user that integrates 
the concepts introduced during previous slides. 


The following slides will 
show, step by step, how 
to create the diagram 
shown here and link it 
to other modules in 
various ways. 

This user's module 
diagram consists of: 

• A Goal G1 

• A Context C2, 
marked public 

• A Strategy SI 

• A Context Cl, 
marked public 

• An Away Goal G2, 
linked to another 
module CPHM 

• And a module 
reference DLPHM 


|£] main-module £3 



A 


C2 ^ 
Hazard 

analysis of the 
aircraft sysla m 


Cl 

An da ntjfja-d hazards 
fo r th b a ircraft sysla m 
ara mitigated 



Argument 
over 

a pa rating . 
p ha ses ■ 


7^ 


C2 

Hazards in the ’cmlse" 
a pa rating phase of the 
a ircraft sysle mare 
mitigated 


fa 


CPHM 


Cl 

Ccncept 
operations for 
the aircraft 
sysiB m 
(Condos) 



3LPHW 


DLPHM 
□Bscent and 
Landing Phase 
Hazards Module 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


To create the main-module 
diagram, the start by employing 
the keyboard shortcuts to add 


nodes Gl, SI, Cl and C2 and then 

|S| main- 

■module 

Ih) t CPHM S3 


fill in their descriptions. 












To link this main-module 












argument to another module 
called CPHM, which has already 












G2 

l-ia rri-o. in 1 h 

P~~i 

' nr i i’z.Ci J 

been created, link the diagrams 
through a goal node with the 
description "Hazards in the 

/ • f . • 1 C . 1 








operating pha&e of the 
a ire raft sysle m a re 
mittgated 














'cruise' operating phase of the 
aircraft are mitigated". This is G2 
inCPHM. 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 

To link the modules, the user: 


1. Navigates to the Goal G2 
in CPHM and marks it 
public in the node's 
Properties. 

2. Next, the user adds an 
Away Goal to the diagram 
and fills in its description. 
Notice at this point that 
the identifier of the away 
goal is AG1. 

3. Next, the user specifies 
which module the Away 
Goal AG1 will link to. The 
menu lists all existing 
public modules in this 
project. The user selects, 
in this case, CPHM. 


§ 


§ 'main-module E CPHM £3 E DLPHM E fcs E C-FITH 


m k 

Hazards in the 'srn-se 
operating phase of the 
a irorafl syste m a re 
mitigated 


"\ 

Co n ee pt of o pa ratio nS ( 
j fo r lha a iroraft systa m 
J (Con Ops) 



fa ma in-mod u la 


Hazards in the "cruise" operating phase of the aircraft system are mitigated 


Problems Tasks O Properties £3 fa Console (^Parameters ( Search 


^ Properties 

Identifier: GZ 

Description: 

Metadata: 

Comment: 

Hyperlinks: 

To Be Instantiated 
To Be Developed 
^ Public 


To Be Supported By Coni 


r- 

Afll ii 

hazards in Lhe smise 
o pa rating pha&s of lha 
a ire raft sysla m a ra 

ii ■* ii 

milgatad. 

El 

CPHM ; t | 


fes 1 

DLPHM 


CP MM fafa/fa 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


4. Next, the user must 
change the away goal 
node's identifier to link G1 
in module CPHM by 
clicking the identifier and 
choosing the appropriate 
goal from the menu of 
public goals in CPHM. 

Notice that the away goal's 
identifier is now G2, matching 
that of the goal that it is 
linking in CPHM. The icon at 
the top right of the node will 
link the two modules directly. 


a5i 

Haza'd-E in the cmsa 
operating pnase of the 
a r D r af l -sysla m a r e 
nil gated. 


CPHM 

■ 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


The main-module diagram now features an away goal linking it to CPHM. Next the user 
wants to add in a reference to another module DLPHM, which has not been created yet. 


§ 


0 main-module £2 


C2 

Hazard 

analysis of the 
aircraft system 


G1 

All identified h azards 
. for the aircraft system 
are mitigated 











<G2 

Hazards in the 'crutB 1 
operating phase of the 
aircraft system are 
mitigated 

fa 

CPHM 




“ jj," 

Hazard 

analysis of the ,■ 

aircraft system / 


C1 fej' 

Concept or 
operations for 
the aircraft 
system 
(Gon-Ops) 



Hazards in the "cruise" 
operating phase of the 
a ire raft syste m are 
mitigated 




Desce 

Landing 

Hazards 

nt and 
j Phase 
. Module 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


The user: 

1. Adds a Module Reference 
Node and includes the name of 
the module to be referenced in 
the node's description. In this 
case, the user wants to 
reference the Descent and 
Landing Phase Hazards Module 
(DLPHM). 

2. Clicking the node's identifier 
will list the menu of all 
available modules to reference. 
Since DLPHM does not exist, it 
isn't on the list, so the user 
selects <New> and names a 
new module DLPHM. This 
automatically opens a new tab 
for that module. 



Descent end 
Lending Phase 
Hazards Module 


m- 


-m- 


Hi 




0 O O New File 

Safetv^Case Module 

Create a safety-case module Mle resource. 


Enter or select the parent folder: 
examples 


jJj 

t3 examples 


Tile name: DLPHM. argument 


Advanced >> 


Cancel 


I Finish | 


@ § * main-module 0 CPHM @ DLPHM £3 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


The user now can create the desired 
DLPHM diagram. The user wants to add a 
goal that is under development and a 
context that links back to the main- 
module diagram. To do so, the user: 

1. Adds a Goal G1 and fills in its 
description. In the G1 node's 
Properties, the user checks the box 
"To be developed" and a green 
diamond appears below the node on 
the diagram. 

2. Adds an Away Context AC1. In the 
dropdown at the bottom of the node, 
the user selects the module to which 
this node will reference. In this case, 
it's the main-module diagram. 

3. Clicks AC1 and specifies which context 
node in the main-module diagram to 
link to. In this case it's Cl. The away 
context node's identifier and 
description automatically populate 
with the Cl node's information. 


§ © ‘main-module g] CPHM [u] -DLPHM S3 



















All identified hazards for the 




for the aircraft syste 
mitigated 

-m are 1 








0 






Cl 


All identified hazards for the descent and landing phases for the aircraft system are mitigated 


Problems y'. Tasks G Properties S3 0 Console Parameters f Search 

Properties 
Identifier: 

Description: 

Metadata: 

Comment: 

Hyperlinks: 

To Be Instantiated 
g To Be Developed 
Public 


-|> 


r 

■ 

— & — 

m ai n- mod u 1 t | 
■ 1 


fcs 

CPHM 

<Mew> 


1 

Cl 

a 

| 




1 > 

C2 

1 


<IN 1 ew> 


1 


1 


■G1 

AH identified haza rds fo r the 
descant and landing phases 
for the aircraft system are 
mitigated 




Do noa ct of o oe ratio n s 
for the aircraft system 
(ConOcs) 


fa main-module 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 

The main-module diagram now resembles the example. Next, the user wants to add some 
elements to the CPHM module diagram. 




ID main-module £3 0 CPHM |E| DLPHM 


V 


C2 

Hazard 

ana Lysis of th a 
a ircraft sysla m 


A 

J 


In — 


ci 

All -danlrfiad hazards 
far ihE aircnafL sys-tem 
ara mrtigatad 


I 


/. ai , / 

. Argument 

avar 

a paneling 
phases 


C2 

hazards in lha "'cruise' 
a pa rating phase af lha 
a irorafl sysla m a re 
mrtigatad 





CPHM 


/ 




~ 1 1 

r 

Descant and 
Landing Phase 
Hazards Module 






1 


1 tn 

a pi of 


Cl 

Con-cep 
o pa ratio ns fa r 
Lha aircraft 
sysla m 
(CanOos) 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


The user wants to create a diagram 

branching off of G2 that includes: 

• An Away Context linking back to 
the main-module diagram from G2 

• A Strategy SI linking from G2 

• An Away Context linking back to 
the main-module diagram from SI 

• A Goal 3 linking from SI 

• A Goal 4 linking from SI 

• A C-FITH contract reference to 
another existing module called C- 
FITH, which in turn references G4 


IhI main-module [h) "CPHM £3 
































G2 P — - 

Hazards in the "cru se r 
operating phase of the 
aircraft syste m a r e 
mitigated 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


These nodes simple additions using 
the keyboard shortcuts. 

To link the away contexts to the main 
module, the user 

1. Selects the main-module from the 
away context's reference menu. 

2. Specifies the desired context node 
in the main-module to reference. 


To add the contract reference node, 
the user: 

1. Clicks the module contract's 
identifier and selects from the 
menu all of the modules 


C-FITH 


C-FITH 




§ main-module 0 CPHM £3 @ C-FITH 


F 1 — I 


C2 

Hazards in the ’crurse 
operating phase of the 
aircraft system a ra 
mitigated 


/ 




/ 


Argument over 
all identified 
hazards for the 
cruse phase 




-N 

3 n ee pt of o p a ratio nS-, 
j fo r the a ircraft systa m 
(Con Ops) 


G3 

Mid-air collision 
hazard is mitigated 




G4 ^ 

Collision with tanra.n 
hazard is mitigated 







main-moduie 


s is x 

Hazard analysis of 
the a ircraft systa m 


fa main-module 




Contract for the fight 
into terrain hazards 
module 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


The user wants to link G4 to the C-FITH 
module diagram via an Away Goal node. To 
do so, G4 must be marked public in CPHM. 
To create this link, the user: 

1. Adds an Away Goal node to the 
desired location in the diagram. 

2. Selects from the reference menu the 
module to link to. In this case, it's 
CPHM. 

3. Clicks the away goal node's identifier 
and selects the Goal G4 node within 
CPHM. The identifier and description 
are automatically updated to match 
CPHM's G4 information. 


§ 1 

0 main- 

■module 

§] CPHM 

@ ‘C- 

FITH El 















































































Ate 


■ CPHM 


main -module 
fcs 

DLPHM 




¥ i— 4 

G4 ▼ 

1 

11 * " 

Collision with terrain 
hazard is mrigated 

<New> 

i 

1 

Pt?] CPHM 

II II II 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


Other notes about the C-FITH module: 

• Notice that the AG1 and AG2 and are 
not associated with any defined 
modules, as they are marked "To be 
developed." 


§ main-module @ CPHM @ C-FITH S3 



terrain \ 


AC 2 

Uncontrolled flight 
into terrain hazard is 
mitigated 


J1 

Collision with t 
can take place in a J 
va riety of see na rios ^ 

i 
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Putting it All Together: Complex Diagram Walkthrough (cont.) 


The user has created a complex diagram spanning several modules by using various links and 
reference tools. How a diagram is broken up is determined by the user. Some diagram 
elements, like the DLPHM reference node and G2 away goal in the main-module diagram, 
perform similar functions (linking to other modules) but can be realized in different ways. 


C2 

Hazard 

analysis of tha 
a ircrafl. syste m 













C2 

Hazards in the "cruise* 
operating phase of the 
a ircraft syste m a re 
mitigated 

fa 

CPHM 



Main-module 


ci 

All identified hazards 
fo r th a a ircraft syste m 
are mitigated 


I 


Argument 

over 

operating 

phases 


Cl 

All identified hazards for the 
descent and landing phases 
fo r the a ircraft syste m a re 
mitigated 




P 


i — i 1 

r 

Desce nt e nd 
Landing Phase 
Hazards Module 






ci 

Consent o 


operations for 
the aircraft 
system 
(ConOps) 


M \ 

F-. r 


C2 

Hazards in the ""cruse 
operating phase of the 
aircraft system are 
mitigated 


TT 


A 


£o n ee pt of o pe ratio ns, 
fo r the a irorafl sysla m 
(ConOos) 


/ 


-It- 


Argument over 
all ideniiflad 
hazards for tha 
cruise phase 


/ 


C3 

Mid-air collision 
hazard is mitigated 


I 


<» Efa 

Collision with terrain 
hazard Is mitigated 


Co n oe pt of o pe ratio n _ 
fo r the a ircraft sysla m 
(ConOps) 


fa men-module 


C^TH 


Contract for lhe flight 
into terrain hazards 
module 


T 


DLPHM 


main-module 


. Hazard analyses of 
the aircraft syste m 


ma in-mod u»e 


CPHM 



C-FITH 
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FM Integration 
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Queries 
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Transformations 
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Transformations 


AdvoCATE currently offers the following transformations: 

1 . Computing metrics: Generates a pre-determined set of metrics on the chosen argument structure 

2. Creating a narrative: Generates a textual representation of the argument structure in a pre-defined format 

3. CSV export: generates a comma-separated-value file in a predefined format for import into a spreadsheet to view a 
tabular representation of an argument structure. 

4. Extracting Assumptions / Evidence / Hyperlinks: Extracts all the assumptions/evidence nodes and the specified 
hyperlinks in all nodes. 

5. Traceability transformations: Lists the traceability links between Goals (with metadata marking them as Hazards, or 
Requirements), Strategies and Evidence. Three types of such links are generated 

a. Hazards to Requirements 

b. Requirements to Strategies 

c. Requirements to Evidence 

6. Task list: Generates a list of incomplete tasks in the argument structure, i.e., nodes marked as undeveloped 


A Transformations can only be applied to argument structures. 
They cannot be applied to argument patterns 
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Launching Transformations 


Some transformations can be launched by selecting the Transformations option on the right-click menu, anywhere on the canvas 


* Advocate - platform Jresource/test-pro]ect/argument-0.acd#/0 - AdvoCATE 


File Edit View Navigate Search Project Run Window 

I r3 - u I <4 ’ I •)"' I 

[q Project Explorer S3 0 ^ ^ □ 

4 L3 gbsaa-sc 
I?] hdb.acp 
Hi top.acd 
d k? test-project 

H argument-O.acd 
H argument-0-G5.acd 
H argument-O-hierarchy.acd 
* L3 test-project-2 

[p] ehdb-pattern.acp 
[p] ha-pattern. acp 


Help 


I o' I 


-• | | - I = | % \ 75% . 


Quick Access 


© | [H Advocate 1 


H argument-0 S3 j 


' Regulatory approval ol 


^ 

/ Regulations have been based 
l on an identification of the 
\. relevant hazards . 



















^ / SI 

7 Argument of 
/ compliance with 
/ regulations / 

% 


\ 



<y Undo Move Shape 
d) Print.. 

Copy 

Paste 

Update 

Remove 

Delete 

Layout Diagram 
View Linked Documents 

Add Node 



Ctrl+F5 

Shift+Delete 


f 02 

GO 


G7 

f Physical \ 

Component A 


Component B 

1 architecture of 1 

failure hazard is 


failure hazard is 

V System A J 

mitigated 


mitigated 


; ffl Miniature View S 


Transformations ► 

Create Narrative 

Search.. 

Show/Hide.. ► 

Create associated diagram 
Hierarchy ► 

View confidence data 
Save as Pattern 

Export Diagram Ctrl+O 

Extract Assumption 
Extract Evidence 
Extract Hyperlink 

Hazards To Requirements 
Requirements To Evidence 
Requirements To Strategies 

Compute Metrics 



5 


Failure hazard of component A 
in operating phase 1 is 
mitigated 



— Problem: < Tasks □ Properties S3 QP Console 


& Connections 

* IsSolvedBy 

* InContextOf 

* HiLink 


v> Palette 


□ 

> i 


Select 

Marquee 


& Objects < 

□Goal 
® Assumption 
O Context 
O Evidence 
^Justification 
O Strategy 
E3 AwayGoal 
0 AwayContext 
Q AwaySolution 
B HiNode 


& Patterns 
ehdb-pattem 
ha-pattem 


Properties 
Node . 


♦ Goal G1 

- 

4- Strategy SI 

a 

^ Assumption A1 


♦ Justification J1 


♦ Context Cl 


♦ Goal G2 

- 


SSS1 
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Adding Transformations to AdvoCATE 

Alternatively, some or all the transformations can be added to the AdvoCATE main menu and task bar 


■ Advocate - p latfor m :/resource/te 
File Edit View Navigate Searc 

I » - Qli a l *4- 1 

[^3 Project Explorer S3 
> & gbsaa-sc 
a £3 test-project 

Hi argument-O. acd 
Hi argument-0-G5.acd 
Hi argument-O-hierarchy.acd 
' £3 test-project-2 

0 ehdb-pattern.acp 
0 ha-pattern acp 


argument-0.acd#/0 - AdvoCATE 





(no launch history) 

Run As 

External Tools Configurations.. 
Organize Favorites... 


S DPI | - 


I <3, <+}, 70% - 


t | [B3 Advocate! 


(U? Miniature View S 







OK 


Cancel 


- Properties 
Node : 


4 Goal G1 
> Strategy SI 
4 Assumption A1 
4 Justification J1 

❖ Context Cl 

♦ Goal G2 


Link : 


Select Launch Configurations: 


SI A Compute Metrics 

Wi A Create Narrative 

S] A Export CSV 

S] A Extract Assumption 

SI A Extract Evidence 

m A, Extract Hyperlink 

SI A Hazards To Requirements 

SI A Requirements To Evidence 

SI A Requirements To Strategies 

SI ATask List 


Select All 


Deselect All 


OK 


Cancel 


Select 
"X Marquee 



& Connections 
IsSolvedBy 
InContextOf 
HiLink 
& Objects 
1=1 Goal 
® Assumption 
*= Context 
O Evidence 
^Justification 
O Strategy 
H AwayGoal 
Q AwayContext 
Q AwaySolution 
□ HiNode 


rf ^ ° □ 


III 


JIBE 


4 Is Solved By Is Solved By 
4 In Context Of In Context Of 


0 


To add transformations 

1 . select from the 
main menu, the 
option Run > 
External Tools > 
Organize Favorites 

2. select Add from 
the dialog box that 
opens 

3. Then select all (or 
the desired) 
transformations 
from the list. 
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Launching Transformations 


After adding transformations, launch them in one of two ways: 

First, select the resource in the project explorer. Then, 

1 . select from the main menu the option Run > External Tools , then select the desired transformation. 


Advocate - platform:Vresource/te^ ^^^/argument-Q.acd#/Q - AdvoCATE 
File Edit View Navigate Searci^^^^B" [ Run 1 Window Help 

jn* _ «i, - 1 >■ 


3-19 


External Tools 


[£} Project Explorer £2 
t> gbsaa-sc 

' test-project 

Hi argument-O. acd 
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0 ha-pattem acp 


B % 


II 


A 1 Compute Metrics 
A 2 Create Narrative 
A 3 Export CSV 
A 4 Extract Assumption 
A 5 Extract Evidence 
A 6 Extract Hyperlink 
A 7 Hazards To Requirements 
A 8 Requirements To Evidence 
A 9 Requirements To Strategies 
A Task List 

Run As 


I 70% - 


Quick Access 



External Tools Configurations ... 
Organize Favorites. 



G5 
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H2 
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Hazard H2 is 
mitigated 
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r — — 


s 


V 


St | [ E Advocate 1 


i> Palette 


k Select 
[’] Marquee 


Connections 
IsSolvedBy 
* InContextOf 
~ * HiLink 


& Objects 
□ Goal 
Gp Assumption 
° Context 


2. Alternatively, run the desired transformation from the Run shortcut on the task bar 


■ Advocate - platform :/resource/test-proJect/argument-0.acd#/0 - AdvoCATE 


File Edit View Navigate Search Project Run Window Help 
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“ □ 

V Palette > 

Select 
[J. Marquee 
& Connections «> 

* IsSolvedBy 
~ 1 > InContextOf 
HiLink 

& Objects «> 

>=lGoal 

Assumption 
O Context 
O Evidence 

•^Justification 
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I I 3-E -9 

A 
A 
A 
A 
A 
A 


[£j Project 
> £3 gbsaa-sc 
a t3 test-project 
Hi argument 
Hi argument 
Hi argument 
* £3 test-project-^ ^ 
0 ehdb-patt 
0 ha-patterrj 


1 Compute Metrics 

2 Create Narrative 

3 Export CSV 

4 Extract Assumption 

5 Extract Evidence 

6 Extract Hyperlink 

7 Hazards To Requirements 

8 Requirements To Evidence 

9 Requirements To Strategies 
Task List 

Run As 

External Tools Configurations... 
Organize Favorites... 
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Configuring Transformations 

Transformations can be configured, so that their output either appears in the Console panel, is written to a specified folder on 
disk, or both. 
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Import and Export 
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Importing Other Formats 

AdvoCATE can import arguments in the D-CASE and ASCE formats. 
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Merging Formal Arguments 

AdvoCATE can create arguments from the output of formal methods tools (currently just AutoCert). 



This feature will change significantly in future. It will be systematized to include other tools. 


AdvoCATE User Guide 


118 


Troubleshooting 
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Troubleshooting 


• Default workspaces 

• What if AdvoCATE opens with all of the panels minimized? 

• Workspace corrupted — create projects external from workspace, re- 
import projects 

• If you can’t move the nodes — collisions 
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